perf(runtime): build struct objects from per-type templates with GC-owned storage - #499

Motivation

Follow-up to #496 (item 7 of its follow-up list). After #496, struct-heavy reads such as UIScreen.mainScreen.bounds.size.width were still ~1.1 µs (native: 55 ns). The remaining cost was the struct object model itself:

• every struct object was built from one shared empty constructor carrying a named interceptor, then re-prototyped with SetPrototype; V8 cannot inline-cache interceptor reads, and each read string-compared the property name against every field
• every read of a nested struct field (rect.size) built a new child wrapper plus a weak handle and finalizer, kept alive by a C++ Persistent to the parent and a ChildCount on the root that made the root's finalizer re-arm
• every struct object was registered with ObjectManager: a Persistent, SetWeak, a list insert, and a finalizer callback on the main thread when it died

Changes

1. A template per struct type. Each struct type gets a FunctionTemplate (cached per isolate in a Caches::StateFor slot keyed by const StructInfo*), with ReadOnlyPrototype() and an instance template carrying one SetNativeDataProperty accessor per field. Struct objects come from that instance template, so they get the constructor's prototype with no SetPrototype, and field access is an inline-cacheable accessor call. CGRect etc. are now the template's function; equals and the type metadata are unchanged.

2. Struct storage owned by the GC, no finalizers. Each struct object holds an ArrayBuffer (internal field) whose external backing store is one malloc block: the StructWrapper constructed in place at its start, followed by the struct bytes when the object owns a copy. The block's deleter runs ~StructWrapper() and then frees it, so V8's ArrayBuffer sweeper destroys the wrapper and reclaims the bytes once the struct object is unreachable (and at isolate teardown for any still alive). V8 may run that deleter on a background thread, so the wrapper's destructor must not touch V8 or the isolate; today it has nothing to release. Struct objects are no longer registered with ObjectManager at all, and a struct can never be reached after its memory is gone, including through an object revived by a finalizer that refuses disposal (a GC-protected NSObject.extend instance).

3. Nested fields stay live views, now cached. A view still aliases its field in the root's bytes (r.size.width = 5 writes into r), but:

   • it is cached in an internal-field slot of its parent, so r.size === r.size and a repeated read costs a slot load;
   • its own storage block holds only the wrapper (pointing into the root's bytes), and it keeps its parent alive through an internal field, so the root's bytes live as long as any view of them.

   This removes the per-read child wrapper and weak handle, ChildCount and the root re-arm, Caches::StructInstances, the struct interceptors and Caches::EmptyStructCtorFunc. Views more than one level deep (r.a.b) are views too; they used to be detached copies.

4. Field assignment. Fields are enumerable now, so Object.assign(a, b) and spreads reach every setter; none of them asserts any more.

   • A struct-typed field accepts a struct of its type (same layout and field names, so a CGPoint is not taken for a CGSize) or a plain object (r.size = { width: 1, height: 2 }), throws a TypeError otherwise, and still reports a released struct. It used to copy the field's size from whatever struct was passed, over-reading a smaller one.
   • A pointer-typed field accepts a Pointer, null, an ArrayBuffer or view, a struct (its address, as before), an interop.Reference (the address it wraps; the Reference is not re-pointed), or a plain object for a struct pointer (snapshotted, as for arguments). Anything else throws a TypeError and leaves the field unchanged; a released native object is still reported.
   • Other field encodings go through Interop::WriteValue instead of Assert(false).
   • Writes through a Proxy around a struct or a view (no traps, or Reflect.set traps as Vue's reactive does) land in the native buffer.

5. Pointer-backed structs don't own the memory. CGRect(pointer) (non-construct call) built a root that freed the pointer's memory on collection, a double free for interop.alloc pointers. It now aliases the pointer's memory and keeps the Pointer object alive.

Behavior changes

Also changed, not observable from JS: struct memory is freed by V8's ArrayBuffer sweeper (possibly off the main thread) instead of a main-thread finalizer, and each struct's block (wrapper + bytes, ~48–80 bytes) counts toward V8's external memory. Native code that keeps a raw pointer from interop.handleof(struct) after JS drops the struct was a use-after-free before and still is; only the moment of the free moves.

The root snapshot is unchanged: a struct returned from native is still a copy (const b = screen.bounds does not track later changes).

Measurements

Release TestRunner, iPhone 16 Pro simulator on an M4 Pro. Main and this branch built and run alternately (main, PR, main, PR) on the same simulator; each figure is the mean of the two rounds, each round the best of 5 × 100k, in ns per op:

Allocation churn: 1M struct objects created in a loop, then a full GC; loop time includes the scavenges it triggers (median of 5 rounds, mean of the two runs):

What remains on the full chain is the method call and two struct object allocations per bounds.size read (root and size view, each with its small storage block); nothing is left to do at collection time.

For reference, the earlier finalizer-based version of this PR, measured back to back against it on the same simulator, was 894 ns for the full chain, 688 ns for screen.bounds.size.width and 453 ns for new CGPoint, with 5–13 ms of full-GC time after each 1M churn; moving the storage into GC-owned ArrayBuffers accounts for that difference.

Validation

• Full TestRunner suite under AddressSanitizer (run_tests.sh -a, dedicated simulator): 0 failures, no sanitizer reports. New RecordTests.js specs cover view identity, write-through in both directions and three levels deep, a deep view keeping its root alive after root and middle view are dropped, collecting 1000 roots with cached views, enumeration/JSON/delete, prototype methods, the complete constructor on a struct that JS never named, Object.assign and plain-object field assignment, rejecting a struct of another type, pointer fields from Pointer/Reference/struct/null, reads and writes through a Proxy (no traps and Reflect traps) checked against a native round trip, and pointer-backed structs not freeing the pointer's memory.
• GCFinalizerTests: the husk spec now forms its husks from interop.References (structs no longer husk) and still checks the released-object report on struct field assignment; a new spec holds only a struct view on resurrected objects and checks it stays readable and writable. The fix(runtime): unwrap Proxy receivers and arguments before native dispatch #485 ProxyReceiverTests run on top of this branch.
• Lifetime specs: a view and a pointer-backed struct keep their bytes through heavy allocation churn and GC; new without an initializer zero-fills.
• Two independent reviews of the finalizer-based version of this PR; their findings (revived views after root disposal, now impossible by construction, constructor completeness for unnamed struct types, a map reference held across allocating calls, setter asserts reachable through Object.assign, a struct-field over-read from a smaller struct, pointer-field asserts, Proxy writes, the pointer-backed free) are addressed in this PR.

Not in this PR

• interop.handleof(view) and passing a view as a pointer argument still hand out a raw pointer into the root's buffer without keeping the root alive, and a pointer-typed struct field holding the address of a Reference, Pointer or struct does not keep that owner alive (unchanged from before).
• Numeric field setters still As<Number>() the value without checking it (unchanged).
• Struct constructors stay anonymous (CGRect.name === ""); anonymous struct types only have synthetic names, so naming them is left out.

Summary by CodeRabbit

• New Features
  • Struct fields can now be accessed through native-backed views, with nested views reflecting writes to their parent.
  • Struct fields support assignment from compatible structs and plain objects, along with expanded pointer-field conversions.
  • Structs without initializers are zero-filled.
• Bug Fixes
  • Struct views and their backing storage remain accessible across garbage collection.
  • Invalid struct field assignments now produce errors.
• Documentation
  • Clarified how struct instances behave during native object finalization.